test: census of standalone toHaveBeenCalledWith sites where the call count is the contract (#15607) - #15782

#!/usr/bin/env node
// Census: `toHaveBeenCalledWith` assertions with no sibling call-count assertion
// on the SAME spy in the SAME `it(`/`test(` block. Run from the repo root:
//   node census.mjs            # summary + per-package split
//   node census.mjs --sites    # one line per standalone site
//   node census.mjs --json
import { readFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { scanSource, blank } from './scripts/js-comment-mask.mjs';

const ROOTS = ['packages', 'examples', 'apps'];
const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;

const argv = process.argv.slice(2);
const filesFlag = argv.indexOf('--files');
const files =
  filesFlag >= 0
    ? argv[filesFlag + 1].split(',')
    : execFileSync('git', ['ls-files', '--', ...ROOTS], { encoding: 'utf8' })
        .split('\n')
        .filter((f) => f && TEST_RE.test(f));

const IDENT = /[\w$]/;

/** Balanced-paren match starting at the '(' at `open` in the structural view. */
function matchParen(code, open) {
  let depth = 0;
  for (let i = open; i < code.length; i++) {
    const c = code[i];
    if (c === '(') depth++;
    else if (c === ')') {
      depth--;
      if (depth === 0) return i;
    }
  }
  return -1;
}

/** Blocks of `it(...)` / `test(...)` calls, innermost-last, as [start,end] spans. */
let noCommentsRef = '';
function testBlocks(code) {
  const spans = [];
  const re = /\b(it|test|bench)\b/g;
  let m;
  while ((m = re.exec(code))) {
    const before = code[m.index - 1];
    if (before && (IDENT.test(before) || before === '.')) continue; // `.it`, `unit`
    // skip an optional `.only` / `.skip` / `.each(...)` / `.concurrent` chain
    let i = m.index + m[0].length;
    for (;;) {
      while (i < code.length && /\s/.test(code[i])) i++;
      if (code[i] !== '.') break;
      let j = i + 1;
      while (j < code.length && IDENT.test(code[j])) j++;
      i = j;
      while (i < code.length && /\s/.test(code[i])) i++;
      if (code[i] === '(') {
        // `.each(...)` or a tagged-template-ish call in the chain
        const close = matchParen(code, i);
        if (close < 0) break;
        i = close + 1;
      }
    }
    while (i < code.length && /\s/.test(code[i])) i++;
    if (code[i] !== '(') continue;
    const close = matchParen(code, i);
    if (close < 0) continue;
    const title = /^[\s(]*(['\"`])([\s\S]{0,160}?)\1/.exec(noCommentsRef.slice(i, i + 240));
    spans.push([m.index, close, title ? title[2].replace(/\s+/g, ' ') : '']);
  }
  return spans;
}

function innermost(spans, offset) {
  let best = null;
  for (const s of spans) {
    if (offset >= s[0] && offset <= s[1]) {
      if (!best || s[0] > best[0]) best = s;
    }
  }
  return best;
}

const norm = (s) => s.replace(/\s+/g, '');

/**
 * The SUBJECT of `expect(...)`: its first argument only.
 * vitest takes an optional second argument as the assertion message
 * (`expect(spy, 'why').toHaveBeenCalledTimes(2)`), and folding that into the
 * spy key made a counted spy look like a different spy from the same spy
 * asserted without a message -- i.e. it reported a COVERED site as standalone.
 */
function firstArg(text) {
  let depth = 0;
  for (let i = 0; i < text.length; i++) {
    const c = text[i];
    if (c === '(' || c === '[' || c === '{') depth++;
    else if (c === ')' || c === ']' || c === '}') depth--;
    else if (c === ',' && depth === 0) return text.slice(0, i);
  }
  return text;
}

/** Every `expect(ARG).CHAIN` in the structural view. */
function expectCalls(code) {
  const out = [];
  // `expect(`, and the modifier forms `expect.soft(` / `expect.poll(`
  const re = /\bexpect\s*(?:\.\s*(?:soft|poll)\s*)?\(/g;
  let m;
  while ((m = re.exec(code))) {
    const before = code[m.index - 1];
    if (before && (IDENT.test(before) || before === '.')) continue;
    const open = m.index + m[0].length - 1;
    const close = matchParen(code, open);
    if (close < 0) continue;
    let i = close + 1;
    let chain = '';
    while (i < code.length) {
      if (/\s/.test(code[i])) { i++; continue; }
      if (code[i] === '.') { chain += '.'; i++; continue; }
      if (IDENT.test(code[i])) { chain += code[i]; i++; continue; }
      break;
    }
    out.push({ at: m.index, arg: norm(firstArg(code.slice(open + 1, close))), chain });
  }
  return out;
}

const COUNT_MATCHER = /toHaveBeenCalledTimes|toHaveBeenCalledOnce/;
const CALLS_LENGTH = /^(.*)\.mock\.calls\.length$/;
const CALLS_ONLY = /^(.*)\.mock\.calls$/;

const sites = [];
const perPkg = new Map();
let totalWith = 0;
let filesScanned = 0;

for (const file of files) {
  const src = readFileSync(file, 'utf8');
  if (!src.includes('toHaveBeenCalledWith')) continue;
  filesScanned++;
  const flags = scanSource(src);
  // structural view: comments AND literal CONTENT blanked, offsets preserved
  const noComments = blank(src, flags.comment);
  const code = blank(noComments, flags.literal);
  noCommentsRef = noComments;

  const lineOf = (off) => src.slice(0, off).split('\n').length;
  const spans = testBlocks(code);
  const calls = expectCalls(code);

  // bare `SPY.mock.calls.length` reads anywhere (not only inside expect)
  const bareCounts = [];
  const bare = /([\w$.\]\[]+)\.mock\.calls\.length/g;
  let bm;
  while ((bm = bare.exec(code))) bareCounts.push({ at: bm.index, spy: norm(bm[1]) });

  const withSites = [];
  const countSites = [];
  for (const c of calls) {
    if (/\btoHaveBeenCalledWith\b/.test(c.chain)) {
      // `.not.toHaveBeenCalledWith` asserts ABSENCE of a matching call, which a
      // repeat cannot satisfy -- it is not the blind idiom this census is about.
      withSites.push({ at: c.at, spy: c.arg, negated: /\.not\b/.test(c.chain) });
      totalWith++;
    }
    if (COUNT_MATCHER.test(c.chain)) countSites.push({ at: c.at, spy: c.arg });
    const mL = CALLS_LENGTH.exec(c.arg);
    if (mL) countSites.push({ at: c.at, spy: mL[1] });
    const mC = CALLS_ONLY.exec(c.arg);
    if (mC && /toHaveLength|toEqual|toStrictEqual|toMatchObject/.test(c.chain))
      countSites.push({ at: c.at, spy: mC[1] });
  }
  for (const b of bareCounts) countSites.push(b);

  const sameBlock = (a, b) => {
    const sa = innermost(spans, a);
    const sb = innermost(spans, b);
    if (!sa && !sb) return true; // both at file scope
    if (!sa || !sb) return false;
    return sa[0] === sb[0];
  };

  for (const w of withSites) {
    const covered = countSites.some((cs) => cs.spy === w.spy && sameBlock(w.at, cs.at));
    if (covered) continue;
    const anywhereInFile = countSites.some((cs) => cs.spy === w.spy);
    const block = innermost(spans, w.at);
    sites.push({
      file,
      line: lineOf(w.at),
      spy: w.spy,
      inTestBlock: Boolean(block),
      test: block ? block[2] : '',
      negated: w.negated,
      countForSpyElsewhereInFile: anywhereInFile,
    });
    const pkg = file.split('/').slice(0, 2).join('/');
    perPkg.set(pkg, (perPkg.get(pkg) || 0) + 1);
  }
}

const args = argv;
if (args.includes('--json')) {
  console.log(JSON.stringify({ filesScanned, totalWith, standalone: sites.length, perPkg: Object.fromEntries([...perPkg].sort((a, b) => b[1] - a[1])), sites }, null, 2));
} else {
  if (args.includes('--sites')) {
    for (const s of sites)
      console.log(`${s.file}:${s.line}\t${s.spy}\t${s.negated ? 'NOT:' : ''}${s.test}${s.inTestBlock ? '' : '\t[not in it()]'}${s.countForSpyElsewhereInFile ? '\t[count elsewhere in file]' : ''}`);
    console.log('');
  }
  console.log(`test files scanned (containing the idiom): ${filesScanned}`);
  console.log(`toHaveBeenCalledWith assertions total:     ${totalWith}`);
  console.log(`STANDALONE (no sibling count, same test):  ${sites.length}`);
  const neg = sites.filter((s) => s.negated).length;
  console.log(`  of which .not.toHaveBeenCalledWith (absence): ${neg}`);
  console.log(`  POSITIVE standalone (the blind idiom):        ${sites.length - neg}`);
  console.log('');
  console.log('per package:');
  for (const [p, n] of [...perPkg].sort((a, b) => b[1] - a[1])) console.log(`  ${String(n).padStart(4)}  ${p}`);
}